Graphics Plus/Graphics Plus.iso/general/raytrace/rayshade/ryshd40n.lha/README.AMIGA

Text File | 1992-11-24 | 7.6 KB | 188 lines

# This is an update version of the readme that came with the original archive


November 23, 1992            Amiga Rayshade Readme (port by Colin DeWolfe)
-----------------

What we have here in this directory is the current release of Rayshade 4.0.  The purpose
of this readme is not to explain the use of Rayshade in general, but to explain how to
use it on the Amiga.  There is nothing really new here except for some '881 code bug fixes
and a co-processorless version (which hopefully work under 1.3, if not, let me know)


Installation
------------

    The only thing you have to do to install rayshade is to copy the file ixemul.library
in the libs directory to LIBS: and add the bin directory to your path.


The Stack
---------

    Rayshade is a stack pig.  The newest release isn't as much of a pig as the older
revisions were (Thanks Craig) but it still loves stack space. Most of the examples in
the Examples directory can be rendered using a stack of under 200,000 but some exhibit
wierd results if they do run out of stack, especially the constructive solid geometry ones.
If rayshade does happen to run out of stack one of three things will happen: 1) it will crash
gloriously, 2) the ixemul.library will trap the error and return gracefully to the shell, or
3) you will just get unpredictable results.  All these seem to depend on how many processes
you have running and if rayshade's stack ends up running over some other program's data.
    Included is a program called StackWatch (James Locker) which will report stack
usage every 30'th of a second.  This is great for examining how much stack Rayshade is
actually using.  It will probably miss alot of peak usage, but it will give you an idea.


Running Rayshade
----------------

    You run Rayshade by using a CLI command of the following form:

1.drive:dir/dir> rayshade < file.ray -O file.mtv [options]

    The documents say that you can use the form "rayshade file.ray > file.mtv [options]"
however I had some trouble supporting this with the GNU C pre-processor and the current version of
ixemul.library, so just use the form above and you will be fine.  I will try to fix this, even if
it means switching to  another pre-processor or SAS libraries.

(aside for this release)

    Rayshade will (no longer) fire up the C pre-processor on your input.  I have removed
this support for the time being, but gcc-cpp is still in the bin directory for
those die-hard include people (and for pre-processing one of the examples). .
You must pre-process the file first, then feed it seperately to the raytracer.
To invoke the preprocessor in the following way

gcc-cpp infile.ray outfile.ray (very important, keep the names different)

(end of aside)

Documentation
-------------

    In the Doc directory are the postscript file for the Guide, Copyright notice,
documentation for some of the support utilities, BUGS, TODO list and other legal stuff.
Some of the utility programs are lacking documentation.  These are: 24toppm, ppmto24,
mtv2tmp, splitanim, and ppmtomtv.  These last three I wrote and have since lost the
source code for (long story).  The other two have notices in the program and did not come
with documentation in the archive that I had.  These will be documented below.

Viewing Pictures
----------------

    Once Rayshade has finished cooking you probably want to look at what it did.
Currently there are three methods for doing this.

1)    run mtvtoppm < file.mtv > pipe:a
    ppmtoilbm -hamforce < pipe:a > file.ilbm
    (Then use your favorite display utility or paint program.)

2)    mtvtoppm < file.mtv > file.ppm
    ppmto24 file.ppm file.iff24
    (This will create a 24 bit iff file for you lucky people with 24 bit boards or A4000's.)

3)  or for preview

    mtv2tmp file.mtv file.tmp         (size limit of 320 400)
    ray2 file                         (note: no extension)

    (Ray2 is taken from DBW Render. It has problems writing a 'correct' ilbm file.
    Most paint programs and AdPro can load it, but most display viewers can't. Go figure.)


Image Mapping
-------------

    Rayshade supports image mapping.  All the details are in the guide, however
I must mention that it likes its input images in the mtv format.  For this reason
the utilities 24toppm, ilbmtoppm, and ppmtomtv are included.  They have usage guides if you
just type their name at the shell prompt or have a doc file in the Doc. directory.



Animations
----------

    Rayshade has built in animation support as documented in the guide.  It is quite
basic however and you will probably end up doing animations using C to generate N input
files.  For those of you who will use the built in animation support, I have included a
program called splitanim which will split up the sometimes huge image file that is
produced (Rayshade renders all the frames of an animation into one long file.)
The usage is as follows:

    splitanim coin.mtv (for the example animation given in the Examples directory)

You will be presented with immense disk activity and then after that, a whole plethora
of files named "*.mtv.n" files where * is the base name (in this case coin) and n is the
frame number.  You can then do with these what you will.


IT'S NOT A BUG, IT'S A FEATURE
------------------------------

    The GCC support for the pipe: device is abysmal.  So, I have given up (for a little
while anyway) supporting the automatic invoking of it from rayshade.  It is however
in the bin directory so that you can preprocess files which need it. (See above)
The reason I am saying that it's a feature is because gcc-cpp will sometimes
embed spaces where you don't want them, i.e., in the middle of a file path.
Rayshade will complain about this. What you can then do is edit the pre-processed file
 to fix this and then feed this file into.

Rayshade will now happily generate your image.
I am going to work on this further, but it may mean moving to another CPP.
Or if anyone has a working version of popen(), mail it to me.


Other Bugs
----------

The projector source code (as far as I can tell) was written with the URT toolkit in mind
and thus renders the image upsidedown. This can be corrected through rotating the light
source (but then it's flipped left to right, just can't win, can we?)  Over XMas I plan to
build in support for the URT libraries, but I have too many midterms to do anything more right now.

Other Notes:
-----------

    Aspect:  try using a fov value of <x> <x/1.3> when you render for ham, this will keep
             everything looking right

    Sampling:The default sampling method is jittered sampling.  For native amiga lo-res displays
             (such as ham), switch to adaptive as the colour resolution is not great and gives you
             fuzzy looking pictures.  If you own an A4000, disregard above.

    A4000:     I have no idea if Rayshade works on an A4000. If you have one, send me info.


Acknowledgements
----------------

For :   Rayshade 4.0:          Craig Kolb of Princeton University

        ppmtoilbm:             The German dudes who ported the great PPM toolkit.
                               You know who you are.  (Blatant plug: Get this thing)

        ppmto24, 24toppm:    A.J. Brouwer

        mtv2tmp, splitanim:    Me.  :-)  (What a self serving little snot, eh?)
        ppmtomtv

        gcc-cpp:        GNU.  Also Markus Wild, who ported it to the Amiga
                        and without who's port of GCC this wouldn't have
                        been possible (SAS and Manx both barfed on the
                        source code.)

        Sustainance:    Ron the Pizza Guy
-------------------------------------------------------------------------------

Mail messages (no money, this is freely redistributable) can be sent to:

Snail (Canada Post):

Colin G. DeWolfe            | email:        [e-mail]
Apt 1115                    |                [e-mail]
1030 South Park St.,         |
Halifax, Nova Scotia        | phone:        [phone]
Canada
B3H 2W3